home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UUndo.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  11.1 KB  |  378 lines  |  [TEXT/MPS ]
  1. // UUndo.h
  2. // Copyright © 1995-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UUNDO__
  5. #define __UUNDO__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __PASCALSTRING__
  10. #include "PascalString.h"
  11. #endif
  12.  
  13. #ifndef __UCOMMAND__
  14. #include "UCommand.h"
  15. #endif
  16.  
  17. #ifndef __ULIST__
  18. #include "UList.h"
  19. #endif
  20.  
  21. #ifndef __UMEMORY__
  22. #include "UMemory.h"
  23. #endif
  24.  
  25. #ifndef __UOBJECT__
  26. #include "UObject.h"
  27. #endif
  28.  
  29. //----------------------------------------------------------------------------------------
  30. // Forward and external class declarations. 
  31. //----------------------------------------------------------------------------------------
  32.  
  33. class TAppleEvent;
  34.  
  35. //------------------------------------------------------------------------------------
  36. // Constants
  37. //------------------------------------------------------------------------------------
  38.  
  39. enum EActionType {kSingleAction, kBeginAction, kEndAction};
  40.  
  41. enum ERespectMarksChoices {kDontRespectMarks, kRespectMarks};
  42.  
  43. //----------------------------------------------------------------------------------------
  44. // CLASS TUndoAction
  45. //----------------------------------------------------------------------------------------
  46.  
  47. class TUndoAction : public TObject
  48. {
  49.     MA_DECLARE_CLASS;
  50.  
  51.   public:
  52.  
  53.     static TUndoAction* NewUndoAction(TCommand* command, EActionType actionType, CommandNumber id);
  54.         // Make an instance of this class. 
  55.  
  56.     //------------------------------------------------------------------------------------
  57.     // Variables
  58.     //------------------------------------------------------------------------------------
  59.  
  60.     TCommand*        fCommand;
  61.     CommandNumber    fID;
  62.     EActionType        fActionType;
  63.     Boolean            fMark;
  64.     
  65.     //------------------------------------------------------------------------------------
  66.     // Initializer, I<Method> and Free.
  67.     //------------------------------------------------------------------------------------
  68.  
  69.     TUndoAction();
  70.                 
  71.     virtual ~TUndoAction();
  72.     
  73.     void IUndoAction(TCommand* command, EActionType actionType, CommandNumber id);
  74.     
  75.     //------------------------------------------------------------------------------------
  76.     // Methods
  77.     //------------------------------------------------------------------------------------
  78.  
  79.     Boolean IsDone();
  80.     
  81. };
  82.  
  83. //----------------------------------------------------------------------------------------
  84. // CLASS TActionStack
  85. //----------------------------------------------------------------------------------------
  86.  
  87. class TActionStack : public TList
  88. {
  89.     MA_DECLARE_CLASS;
  90.  
  91.   public:
  92.  
  93.     static TActionStack* NewActionStack();
  94.         // Make an instance of this class. 
  95.  
  96.     //------------------------------------------------------------------------------------
  97.     // Initializer, I<Method> and Free.
  98.     //------------------------------------------------------------------------------------
  99.  
  100.     TActionStack();
  101.                 
  102.     virtual ~TActionStack();
  103.     
  104.     void IActionStack();
  105.     
  106.     //------------------------------------------------------------------------------------
  107.     // Methods
  108.     //------------------------------------------------------------------------------------
  109.  
  110.     inline TUndoAction* Top()    { return (TUndoAction*) Last(); }
  111.     
  112.     inline TUndoAction* PopAction()    { return (TUndoAction*) Pop(); }
  113.     
  114.     void PushAction(TUndoAction* action);
  115.  
  116.     void ClearActionsToMark();
  117.         // Delete and free actions until a marked one is found, or the stack is empty. 
  118.     
  119.     TUndoAction* FindTransaction(TCommand* command, Boolean itsForward);
  120.         // Find the action or transaction containing a command. 
  121.         // Use kIterateForward for the undo stack, kIterateBackward for redo. 
  122.  
  123.     Size PurgeFirstPhase(Size needed) { return Purge(needed, 1); }
  124.         // Unload as much of the stack as needed up to, but not including,
  125.         // the topmost entry in the stack.
  126.  
  127.     Size Purge(Size needed, ArrayIndex numToLeave = 0);
  128.         // Unload up to top.
  129.  
  130. private:
  131.     // We need to better tune the following number.  This number indicates what we would like
  132.     // to be the maximum number of stacked undoable actions at any one time.  If your commands
  133.     // retain large amounts of data for performing undo/redo then you may want to reduce this
  134.     // limit.  If they are smaller then perhaps the number could be increased.  We should also
  135.     // consider having a maximum memory usage setpoint as well but the overhead of keeping
  136.     // a running total is too costly right now.
  137.  
  138.     static const ArrayIndex sMaxDesiredItems;    // Maximum number of entried in stack.
  139. };
  140.  
  141. //----------------------------------------------------------------------------------------
  142. // CLASS TUndoHandler
  143. //----------------------------------------------------------------------------------------
  144.  
  145. class TUndoHandler : public TObject
  146. {
  147.     MA_DECLARE_CLASS;
  148.     
  149.   public:
  150.  
  151.     static TUndoHandler*    fgUndoHandler;    // The undo handler object. 
  152.  
  153.     static void InitUUndo();
  154.         // Initialize this unit. 
  155.  
  156.     static TUndoHandler* NewUndoHandler();
  157.         // Make an instance of this class. 
  158.         
  159.     //------------------------------------------------------------------------------------
  160.     // Variables
  161.     //------------------------------------------------------------------------------------
  162.  
  163.   protected:
  164.  
  165.     TActionStack*        fUndoStack;                // Stack of commands that could be undone. 
  166.     TActionStack*        fRedoStack;                // Stack of commands that could be redone. 
  167.     long                fInTransaction;            // Keep track of transaction level in case
  168.                                                 // we need to abort. 
  169.     
  170.     //------------------------------------------------------------------------------------
  171.     // Initializer, I<Method> and Free.
  172.     //------------------------------------------------------------------------------------
  173.  
  174.   public:
  175.  
  176.     TUndoHandler();
  177.                 
  178.     virtual ~TUndoHandler();
  179.     
  180.     void IUndoHandler();
  181.     
  182.     //------------------------------------------------------------------------------------
  183.     // Action History Manipulation
  184.     //------------------------------------------------------------------------------------
  185.  
  186.     void AddActionToHistory(TCommand* command, EActionType actionType, CommandNumber id);
  187.         // Add an action to the list of commands that could be undone. 
  188.         // Also clears the redo history. 
  189.     
  190.     void BeginAction();
  191.         // Add an begin action to the list of commands that could be undone. 
  192.         // Also clears the redo history. 
  193.     
  194.     void EndAction();
  195.         // Add an end action to the list of commands that could be undone. 
  196.         // Also clears the redo history. 
  197.     
  198.     void AbortCurrentTransaction();
  199.         // Remove the current transaction (and any nested transactions) from
  200.         // the action history. Must be called before the End action is added. 
  201.     
  202.     void ClearActionHistory(ERespectMarksChoices respectMarks);
  203.         // Clear the undo and redo stacks. 
  204.     
  205.     void MarkActionHistory();
  206.         // Marks the top of the undo and redo stacks. 
  207.     
  208.     TUndoAction* FindTransaction(TCommand* command);
  209.         // Find the action or transaction containing a particular command. 
  210.     
  211.     void Abort();
  212.         // Abort the top (trans)action in the undo stack. 
  213.     
  214.     Size Purge(Size needed);
  215.         // Unload as much of the undo and redo stack as needed.
  216.  
  217.     //------------------------------------------------------------------------------------
  218.     // Undo
  219.     //------------------------------------------------------------------------------------
  220.  
  221.     void Undo();
  222.         // Undo the top (trans)action in the undo stack. 
  223.     
  224.     Boolean AnythingToUndo();
  225.         // Whether there is anything to undo on the stack. 
  226.     
  227.     CommandNumber GetUndoID();
  228.         // Get the ID for the undo menu item for a command. 
  229.     
  230.     void GetUndoText(CStr255& undoName);
  231.         // Get the text for the undo menu item for a command. 
  232.     
  233.     //------------------------------------------------------------------------------------
  234.     // Redo
  235.     //------------------------------------------------------------------------------------
  236.  
  237.     void Redo();
  238.         // Redo the top (trans)action in the redo stack. 
  239.     
  240.     void ClearRedoHistory();
  241.         // Clear the redo stack. 
  242.     
  243.     Boolean AnythingToRedo();
  244.         // Whether there is anything to redo on the stack. 
  245.     
  246.     CommandNumber GetRedoID();
  247.         // Get the ID for the redo menu item for a command. 
  248.     
  249.     void GetRedoText(CStr255& undoName);
  250.         // Get the text for the redo menu item for a command. 
  251.     
  252.     //------------------------------------------------------------------------------------
  253.     // For internal use only
  254.     //------------------------------------------------------------------------------------
  255.  
  256.   protected:
  257.  
  258.     EActionType AbortAction();
  259.         // Abort the top action in the undo stack. 
  260.     
  261.     void AbortCommand(TCommand* command);
  262.         // Abort a command. 
  263.     
  264.     EActionType UndoAction();
  265.         // Undo the top action in the undo stack. 
  266.     
  267.     void UndoCommand(TCommand* command);
  268.         // Undo a command. 
  269.     
  270.     EActionType RedoAction();
  271.         // Redo the top action in the undo stack. 
  272.     
  273.     void RedoCommand(TCommand* command);
  274.         // Redo a command. 
  275. };
  276.  
  277. //----------------------------------------------------------------------------------------
  278. // CLASS TUndoRedoCommand
  279. //----------------------------------------------------------------------------------------
  280.  
  281. class TUndoRedoCommand : public TCommand
  282. {
  283.     MA_DECLARE_CLASS;
  284.     
  285.   protected:
  286.     
  287.     AEEventID    fAEEventID;
  288.     
  289.   public:
  290.     
  291.     TUndoRedoCommand();
  292.         // Constructor
  293.     virtual ~TUndoRedoCommand();
  294.         // Destructor
  295.             
  296.     void IUndoRedoCommand(CommandNumber itsCommandNumber);
  297.         // Initialize the UndoRedoCommand procedurally.
  298.  
  299.     virtual TAppleEvent* MakeAppleEvent();
  300.         // Create a Undo or Redo Apple Event. 
  301. };
  302.  
  303. //----------------------------------------------------------------------------------------
  304. // CLASS TUndoCommand
  305. //----------------------------------------------------------------------------------------
  306.  
  307. class TUndoCommand : public TUndoRedoCommand
  308. {
  309.     MA_DECLARE_CLASS;
  310.     
  311.   public:
  312.     
  313.     TUndoCommand();
  314.         // Constructor
  315.     virtual ~TUndoCommand();
  316.         // Destructor
  317.             
  318.     void IUndoCommand(CommandNumber itsCommandNumber);
  319.         // Initialize the UndoCommand procedurally.
  320.  
  321.     virtual void DoIt();
  322.         // tell the application to undo/redo.
  323. };
  324.  
  325. //----------------------------------------------------------------------------------------
  326. // CLASS TRedoCommand
  327. //----------------------------------------------------------------------------------------
  328.  
  329. class TRedoCommand : public TUndoRedoCommand
  330. {
  331.     MA_DECLARE_CLASS;
  332.     
  333.   public:
  334.     
  335.     TRedoCommand();
  336.         // Constructor
  337.     virtual ~TRedoCommand();
  338.         // Destructor
  339.             
  340.     void IRedoCommand(CommandNumber itsCommandNumber);
  341.         // Initialize the RedoCommand procedurally.
  342.  
  343.     virtual void DoIt();
  344.         // tell the application to undo/redo.
  345. };
  346.  
  347. //----------------------------------------------------------------------------------------
  348. // CLASS CUndoStackHook
  349. //----------------------------------------------------------------------------------------
  350.  
  351. // A class for unloading portions of the undo stack when memory is needed.
  352.  
  353. class CUndoStackHook : public CGrowZoneHook
  354. {
  355.   public:
  356.     CUndoStackHook() { }
  357.     virtual ~CUndoStackHook() { }
  358.  
  359.     virtual Size TotalSize(Boolean justLocked);
  360.         // Returns the total number of bytes managed (or only locked
  361.         // handles if justLocked is true). 
  362.  
  363.     virtual Size Purge(Size needed);
  364.         // Make memory available by unloading the undo stack. Returns 
  365.         // the actual amount of memory purged. 
  366. };
  367.  
  368.  
  369. //========================================================================================
  370. // GLOBAL Procedures
  371. //========================================================================================
  372.  
  373. void GetUndoRedoText(Boolean cmdDone, CommandNumber aCommandNumber, CStr255& undoName);
  374.     // Get the text for the undo or redo menu item for a command. 
  375.     
  376.  
  377. #endif // __UUNDO__
  378.